每一家公司針對業務與營運上的需求，對於現行運作中的系統多少都會有功能的調整與新增，由於人員可能異動，或系統可能大幅調整，如果文件沒有跟著更新，隨著人員的異動，久而久之就沒有人曉得當初是為了什麼原因而進行調整的（這也是現在檢討流程時的困擾）。
稽核重點：重大需求變更是否更新系統相關文件。
提供資料：系統相關文件（使用手冊、操作手冊、SOP、教育訓練文件等）
我曾經這樣想過，如果有一套完美的系統，這樣所有系統的問題都迎刃而解，程式開發人員也不用這麼辛苦了
這麼多年下來，我發現夢終究還是夢，IT依然是挨踢...
...這就跟每個男人都希望擁有一個完美情婦（誤）完美嬌妻一樣...啊...我的補教人生...咳...回歸主題
寫文件、寫手冊，相信一定是程式開發人員的夢靨，為什麼程式要愈寫愈簡潔，而文件卻要愈寫愈厚重？誰會看？誰又想看呢？
可是如果你問剛進公司的新人，他最需要的是什麼，他一定回答你系統的使用文件或Help
這就是程式開發人員與使用者間的鴻溝，如何將程式運作的邏輯讓使用者可以很容易的了解，這就是我們製作文件的目的。
那麼，文件的內容應該包含哪些呢？與其天馬行空，隨興而寫，不如遵循一些基本的原則，讓文件的可讀性提高，這樣文件的製作才有意義與價值。
當然要花多少時間製作文件，可能見仁見智。但文件能否被妥善的管理，則就相形重要了。
首先，我們從文件的封面看起。（謎之音：封面不就是文件標題？）如果是這樣，就太粗淺了！除了文件標題，應該還有文件的版本、發行日期、文件的狀態（如 Draft 或 Released等）、撰寫者、審查者、核定者等資訊，甚至文件的編號，如果有導入 ISO 文管制度或 CMMI，可依其格式辦理；不過老實說，人數規模沒有大到那種程度，做這些反而累死自己。所幸，審計查核重點並不在文件的格式或製作方式，主要是看 ERP 系統的增修，是否有相關的文件可以參考與傳承。
接下來應該有 Change Log（文件修訂記錄），記錄修訂日期、版本與修改內容。這些都是很好的追蹤記錄與管理方式（如果有文管系統則更理想）。
文件的目的、摘要，說明本文件的用途，內容的部份依實際需要撰寫即可，畢竟資訊單位不是軟體公司承接專案，需依軟體/專案開發所需文件格式撰寫。如果真要參考範本，像以前資策會出的 SDG 2.0（看到這個名詞就可以知道我的年代久遠...
），經濟部的軟體技術文件指引，都有很完整的規範與範例可以參考。
關於 SDG 2.0 的始末可以參考這一篇：即將走出人們視野外的 SDG 2.0
寫文件比不寫文件要難
而比寫文件要難的
就是更新文件了
老外最愛寫文件，強調文件的重要性
我們最恨寫文件，寫文件既煩又沒用
有沒有兩全其美的方法？
我唯一能想到的最佳解決方案
就是"文件自動產生器"
最好的例子就是像JavaDoc的機制
可以先宣告各function的IPO定義當成規格
然後寫程式
如果之後有修改程式
只要修改宣告部份的Tag
就可以按一個鍵產生程式文件
不但文件內容與程式內容相符合
程式員也不必重覆花時間寫文件
有一部分如程式說明文件用這種方式產生就很適合，尤其是政府的專案很喜歡叫人家提供這種文件
但是，他們又不寫程式，也不知道產生這種文件對他們有什麼幫助，對開發廠商比較有幫助才對
把程式碼與商業邏輯寫好後都存到資料庫,系統執行時再到資料庫撈程式碼去演譯,這樣程式碼與商業邏輯的管理就可透過資料庫來進行,除此以外,架構圖與流程圖也一併存到資料庫,這樣包含程式碼與商業邏輯都可以透過圖來管理,並且直接線上驗證系統,會很方便.
寫文件,我最討厭寫文件了.
為了寫文件而文件?
坦白說,你要什麼文件我都可以做給你.
以我程設師的觀點.
修了文件改Code.
修了Code改文件.
到最後Code跟文件根本是二馬子的事.
有時文件很簡單,但寫成Code很複雜.這我認了.
有時Code很簡單,但換成文件就很複雜.有時不只是文字還要畫架構圖,有時要寫學術論文..
寫Code30分,寫文件花3小時,什麼跟什麼?
坦白說寫Code不一定寫文件.
Code寫的好.名稱寫的好,流程有順序,一看就懂.
但台灣人英文就是差.名字取A1,A2,A3....然後寫一推註解這個變數在做什麼.
我以前接手一個中興大學畢業的碩士寫的資料庫.裡面有一個欄位叫做Big2.我怎麼看都看不懂又沒文件可以看.我叫他補文件.原來是大哥大的號碼!
然到你不會取CellPhone,MobilePhone,PhoneNumber??????這樣你不寫文件我都看的懂.
可以感覺您很不喜歡寫文件,大概習慣從code就可看到設計流程或原意.
但角色不同或許立場也會不同,以前要求設計師下班前寫日誌,貼在後勤論壇,包含事件主旨原委,處理概念,最後再貼上程式碼.為甚麼?因為他做了甚麼,是否聽懂交辦的事情,可從論述去了解,再從其預下的SQL指令,程式主體去看,是否作對做錯,可以在事前就作比較有效的稽核.
少了文件紀錄,為了解決事情,一樣是要花時間去問他將程式碼放在哪一段,再看其程式碼,工作量也是差不多,但程式碼沒有整件事情概觀,一件事情可能有多筆相關程式碼,要從事件需求去管理分散的相關程式碼,除非也作紀錄,不然要反推也不容易,而看的可能又是比較資深而成本高的人,這樣反而工作成本比較多.
而最重要的是,多年後客戶需求變更需要維護時,可能人事已非,如果不巧該事很複雜,要依靠當初主事的程設師,是否也要其離職後接電話回答相關疑問?而他是否有那個義務回答就是個風險,而新人要接手,又要從一堆散亂的程式檔中去翻找,找出來以後,還要再對事情原委解說與交辦一次,僅就系統成本與效率的考量,這樣的作法都不是很恰當.如果當初有處理事件的文件,可追蹤參考,可延續紀錄,對於客戶的後勤與新人的交接,都可以省下不少工作成本.
寫Code30分,寫文件花3小時,對我而言,這不是什麼跟什麼,而是一件蠻重要的事.
文件很重要是沒錯,但~
已我這幾年的IT觀察.
IT的速度越來越快.
一個Case,一個客戶,一個職員,一間公司,那麼多年,真的是不簡單.
在台灣,老闆炒短線,員工炒短線.
老闆將員工當什麼使用?用完了就丟,員工看不到未來.
員工也是打帶跑的心態,有什麼老闆就有什麼員工.
一個客戶要能維護那麼多年,這份情感真的.
就寫軟體,前一版的技術跟後一版的技術會非常的不同.就維護合約通常也是一年一簽.
如果說一個Case在多年後出問題要修改.要找到原系統文件也不簡單.通常需要在需求訪談或舊系統在Run過一遍後整個或部分系統重構.
//寫Code30分,寫文件花3小時,對我而言,這不是什麼跟什麼,而是一件蠻重要的事.
對你很重要,但就整個系統開發,你要考量時間跟成本.如果貴公司資源很多.跟中研院/中科院/工研院一樣,你就可以每天寫研究報告.
當老闆的好像都被您講的不是人了,我在猜,如果系統都是靠程式碼去堆積,當老闆的也只好拼命請程設師,然後年年不斷在產生程式碼,這些日積月累的程式碼終究會改變老闆作法,而開始一些短線的操作,當員工精疲力竭陷入程式碼堆,相對性也會猜面臨管理困境老闆可能出招,難免會想像有被無情丟棄的危機,這不就是一種惡性循環嗎?如果系統不是這樣,然後又很賺錢,或許就不會每個老闆都被您形容成這麼惡劣.
文件對於我而言主要的目的是要從中篩選整理出業務用文件,有機會讓未來的客戶線上看到系統的成形過程,是靠系統規劃與系統分析來建構的.為此我自己還在抽空寫我的 WEB 便利貼,希望能將一些分析結果貼在 WEB 上,讓系統的主體架構與細節處理都能夠呈現出來.
http://ithelp.ithome.com.tw/question/10039800
我們主要作商業資料庫應用專案,有些客戶維護合約已經超過10年了,還好在維護工作上也不是甚麼大問題,不過倒不是有文件的關係,而是我們的系統可用於所有不同類型的客戶,像進銷存與人事薪資,出口貿易等不同類型的產業或機關,系統有95%左右是一樣的,商業邏輯都存在客戶資料庫,然後動態在執行,所以專案大約都可控制在約3千列以內程式,其餘的都是資料庫定義好,版面排一排就可以了.新版的 WEB 甚至都將操作版面也一併存到客戶資料庫,以讓系統更輕巧,更方便整合管理.
因為系統很小,所以系統出問題的機率不高,幾乎都是在處理客戶新增的需求.所以雖然我沒有如工研院般的人力與資源,但面對所有新舊客戶的維護外,還是在想辦法不斷寫文件,目的之一也是希望有朝團隊成員增加時,能夠在不花太多時間成本上交接事情,並提供新進人員的工作參考.
我的後勤網雖然只有我一人在寫,但我還是會繼續寫,並邀請客戶也進來看,如果可以跟客戶形成互動,也算是溝通需求與討論問題的一種方法.
以前做專案的時候，有兩份文件是審查的重點：使用手冊與操作手冊。
這兩個文件很容易混淆，一個是給使用者看的，一個是給維護單位看的。
就我以前的認知，給使用者看的是使用手冊，給維護人員看的是操作手冊。但是後來的經驗，好像這兩者被混在一起了。
給使用者看的文件，偏重功能的解說，與畫面的操作及畫面的欄位說明；給維護人員看的也會有前述的說明，但會搭配 Table Schema 及參數設定等說明文件。
做文件真的很累，以前在軟體公司就有專門製作文件的部門（而且是多國語言），使用 help 製作工具來做線上 help 文件（當時沒有深入去了解該部門的作業方式，所以知道的不多），研發人員根本不用去管這個東西。
但現在在MIS單位，說真的能省則省，文件大部分都存在每個需求申請單當中...這也是值得去改善的項目之一。
只要是MIS, 沒人會喜歡寫文件.
通常寫文件只是備查, 實用性通常不高. 一來MIS角度寫的, USER不一定看的懂, 二來即時更新, 不容易做到. 這是文件經常遇到的狀況.
針對每個工作(也就是程式), 不妨提供MIS跟特定USER可以修改文件的功能, 初期MIS編寫基本描述, USER根據工作實務補充相關細節以及後續變更記錄, 這樣也許可以增加文件實用性.
PS: 基本操作跟工作流程圖, 因為修改狀況不多, 所以還是得MIS來編寫.
擔任MIS多年，資訊主管也多年，個人覺得，文件還是要做
如果不想做？
1.考慮人事、組織
2.依據上述條件，調整文件
例如，真的沒人，那就折衷一下，直接在程式碼裡面加上附註，只要讓另一個不相關的Programer看得懂即可。
IT人員異動難免，只能做好『備援』計畫。
iThome鐵人賽
看影片追技術